home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / Edb.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-01-09  |  12.1 KB  |  375 lines
  1. #ifndef EDB_H
  2. #define EDB_H 1
  3.  
  4. #ifdef EAPI
  5. #undef EAPI
  6. #endif
  7. #ifdef WIN32
  8. # ifdef BUILDING_DLL
  9. #  define EAPI __declspec(dllexport)
  10. # else
  11. #  define EAPI __declspec(dllimport)
  12. # endif
  13. #else
  14. # ifdef __GNUC__
  15. #  if __GNUC__ >= 4
  16. #   define EAPI __attribute__ ((visibility("default")))
  17. #  else
  18. #   define EAPI
  19. #  endif
  20. # else
  21. #  define EAPI
  22. # endif
  23. #endif
  24.  
  25. #ifdef __cplusplus
  26. extern "C" {
  27. #endif  
  28.  
  29.  
  30. /* The basic db handle */
  31. typedef void        E_DB_File;
  32.  
  33. /* Edb Core Functions .............................. */
  34.  
  35. /**
  36.  * e_db_open - Opens a db for read/write access
  37.  * @file: name of the db file.
  38.  *
  39.  * This function opens an edb database file for read
  40.  * and write access. It returns NULL if not possible,
  41.  * a pointer to an E_DB_File otherwise.
  42.  */
  43. EAPI E_DB_File          *e_db_open(const char *file);
  44.  
  45. /**
  46.  * e_db_open_mode - Opens a db with a user-specified mode
  47.  * @file: name of the db file.
  48.  * @flags: bitmask in the format specified by open(2)
  49.  *
  50.  * This function opens an edb database file for access as specified by
  51.  * flags. It returns NULL if not possible, a pointer to an E_DB_File
  52.  * otherwise.
  53.  */
  54. EAPI E_DB_File          *e_db_open_mode(const char *file, int flags);
  55.  
  56. /**
  57.  * e_db_property_set - Sets the value of a Property Field.
  58.  * @edb: A database handle.
  59.  * @property: The name of the Property Field to edit.
  60.  * @value: The value to assign the the field.
  61.  *
  62.  * The property fields are special database fields that cannot be accessed
  63.  * by the normal get/set methods. They are used to store meta-data about the
  64.  * database (e.g. Type and Version Information). This function will set the
  65.  * value of a specified property field.
  66.  */
  67. EAPI void                e_db_property_set(E_DB_File *edb, const char *property, const char *value);
  68.  
  69.  
  70. /**
  71.  * e_db_property_get - Gets the value of a Property Field.
  72.  * @edb: A database handle.
  73.  * @property: The name of the Property Field to edit.
  74.  *
  75.  * This function will retrieve the data stored in the specified property
  76.  * field.
  77.  */
  78. EAPI char                *e_db_property_get(E_DB_File *edb, const char *property);
  79.  
  80. /**
  81.  * e_db_set_type - Convenience function for setting the value
  82.  * of the Type Property Field.
  83.  * @edb: A database handle.
  84.  * @value: The value to append to the current Type Property.
  85.  *
  86.  * This function sets the value of the Type Property for the current database.
  87.  * If there is already a value in the type field this value will be appended
  88.  * to the end. Each type is seperated by a '/' character with the entire
  89.  * string having leading and trailing seperating characters. The function adds
  90.  * the seperation characters itself.
  91.  */
  92. EAPI void                e_db_set_type(E_DB_File * edb, const char *value);
  93.  
  94. /**
  95.  * e_db_is_type - Convenience function for determining if a database is
  96.  * of a certain type.
  97.  * @edb: A database handle.
  98.  * @type: The type string to check for.
  99.  *
  100.  * This function will compare the specified type string against the type
  101.  * data stored in the database. If a match is found (case-insensitive) then 1
  102.  * is returned, else 0.
  103.  */
  104. EAPI int                 e_db_is_type(E_DB_File * edb, const char *type);
  105.  
  106. /**
  107.  * e_db_open_read - Opens a database for read access only
  108.  * @file: name of the database file
  109.  *
  110.  * This function opens an edb database file for read access.
  111.  * It returns NULL if that's not possible, a pointer to an
  112.  * E_DB_File otherwise.
  113.  */ 
  114. EAPI E_DB_File          *e_db_open_read(const char *file);
  115.  
  116.  
  117. /** 
  118.  * e_db_close - Closes a db handle
  119.  * @db: Edb database handle
  120.  *
  121.  * This function closes a database. It does not guarantee a
  122.  * write to disk, it just decrements the use count on the
  123.  * database. When a database has been closed by all users,
  124.  * calling e_db_flush() writes the database to disk.
  125.  */
  126. EAPI void                e_db_close(E_DB_File * db);
  127.  
  128. /**
  129.  * e_db_data_get - Retrieves generic data from the db for a given key
  130.  * @db: Edb database handle
  131.  * @key: key for the data item
  132.  * @size_ret: result parameter that returns the size of the data item
  133.  *
  134.  * This function is the generic way to retrieve data from
  135.  * an Edb database. Use the @size_ret value to find out the
  136.  * size of the retrieved data. Returns the retrieved data,
  137.  * which you need to free when you don't need it any longer.
  138.  */
  139. EAPI void               *e_db_data_get(E_DB_File * db, const char *key, int *size_ret);
  140.  
  141. /**
  142.  * e_db_data_set - Writes generic data to a database
  143.  * @db: Edb database handle
  144.  * @key: Key through which the data can be retrieved
  145.  * @data: the data item itself
  146.  * @size: size of the data item @data
  147.  *
  148.  * This function is the generic way to write items of data to a
  149.  * database. 
  150.  */
  151. EAPI void                e_db_data_set(E_DB_File * db, const char *key, const void *data, int size);
  152.  
  153. /**
  154.  * e_db_data_del - Removes a key-data pair in a database
  155.  * @db: Edb database handle
  156.  * @key: Key that determines the data item that is removed
  157.  *
  158.  * This function removed the key and data in a database that
  159.  * the given key points to.
  160.  */
  161. EAPI void                e_db_data_del(E_DB_File * db, const char *key);
  162.  
  163. /**
  164.  * e_db_usage - returns the number of database files a process uses
  165.  *
  166.  * This function returns the number of database files the
  167.  * current process is using at the moment.
  168.  */
  169. EAPI int                 e_db_usage(void);
  170.  
  171. /**
  172.  * e_db_flush - flushes the contents of unused databases to disk
  173.  * 
  174.  * This function checks for which databases the use count has
  175.  * dropped to zero and writes their contents out to disk.
  176.  */
  177. EAPI void                e_db_flush(void);
  178.  
  179. /**
  180.  * e_db_runtime_flush - time-sensitive version of @efsd_db_flush
  181.  *
  182.  * This function is like @efsd_db_flush, but flushes databases
  183.  * only if they have not been accessed in the last 0.5 seconds.
  184.  * It returns 1 if the databases have been flushed, 0 otherwise.
  185. */
  186. EAPI int                 e_db_runtime_flush(void);
  187.  
  188. /* High-level convenience functions ................... */
  189.  
  190.  
  191. /**
  192.  * e_db_int_set - convenience function for writing integers to a database
  193.  * @db: Edb database handle
  194.  * @key: key through which the data can be retrieved
  195.  * @val: the integer value that is to be written to the database
  196.  *
  197.  * This function is a convenience wrapper around e_db_data_set() to
  198.  * set integer values in a database. It also handles endianness
  199.  * byteorder flips.
  200.  */
  201. EAPI void                e_db_int_set(E_DB_File * db, const char *key, int val);
  202.  
  203. /**
  204.  * e_db_int_get - convenience function for retrieving integers from a database
  205.  * @db: Edb database handle
  206.  * @key: key for the integer value
  207.  * @val: result value that points to an integer where the result is stored
  208.  *
  209.  * This function retrieves an integer for the given key from a database,
  210.  * handling endianness flips. It returns 1 if the lookup succeeded, 0 otherwise.
  211.  */
  212. EAPI int                 e_db_int_get(E_DB_File * db, const char *key, int *val);
  213.  
  214. /**
  215.  * e_db_float_set - convenience function for writing floats to a database
  216.  * @db: Edb database handle
  217.  * @key: key through which the data can be retrieved
  218.  * @val: the float value that is to be written to the database
  219.  *
  220.  * This function is a convenience wrapper around e_db_data_set() to
  221.  * set float values in a database. It also handles endianness
  222.  * byteorder flips.
  223.  */
  224. EAPI void                e_db_float_set(E_DB_File * db, const char *key, float val);
  225.  
  226. /**
  227.  * e_db_float_get - convenience function for retrieving floats from a database
  228.  * @db: Edb database handle
  229.  * @key: key for the integer value
  230.  * @val: result value that points to a float where the result is stored
  231.  *
  232.  * This function retrieves a float for the given key from a database,
  233.  * handling endianness flips. It returns 1 if the lookup succeeded, 0 otherwise.
  234.  */
  235. EAPI int                 e_db_float_get(E_DB_File * db, const char *key, float *val);
  236.  
  237. /**
  238.  * e_db_str_set - convenience function for writing strings to a database
  239.  * @db: Edb database handle
  240.  * @key: key through which the data can be retrieved
  241.  * @str: the string that is to be written to the database
  242.  *
  243.  * This function is a convenience wrapper around e_db_data_set() to
  244.  * set character strings in a database.
  245.  */
  246. EAPI void                e_db_str_set(E_DB_File * db, const char *key, const char *str);
  247.  
  248. /**
  249.  * e_db_str_get - convenience function for retrieving strings from a database
  250.  * @db: Edb database handle
  251.  * @key: key for the integer value
  252.  *
  253.  * This function retrieves a string for the given key from a database
  254.  * and returns it. When an error occurs, NULL is returned. You must free
  255.  * the string when you're finished using free().
  256.  */
  257. EAPI char               *e_db_str_get(E_DB_File * db, const char *key);
  258.  
  259. /**
  260.  * e_db_type_set - sets the encoding of a database item
  261.  * @db: Edb database handle
  262.  * @key: key for the data item whose type is to be set
  263.  * @type: string containing the type of the data item
  264.  *
  265.  * This function sets the type of a database entry. The types currently
  266.  * used are "int" for integers, "str" for strings and "float" for
  267.  * floats. All other types are application-specific. You do not need to
  268.  * set the types manually when using e_db_int_set(), e_db_float_set()
  269.  * and e_db_str_set().
  270.  */
  271. EAPI void                e_db_type_set(E_DB_File * db, const char *key, const char *type);
  272.   
  273. /**
  274.  * e_db_type_get - returns type of a data item
  275.  * @db: Edb database handle
  276.  * @key: key for the data item whose type is retrieved
  277.  *
  278.  * This function returns the type of a data item in a database. If
  279.  * the type is unknown, NULL is returned. Otherwise, you need to 
  280.  * free the result when you're finished, using free().
  281.  */
  282. EAPI char               *e_db_type_get(E_DB_File * db, const char *key);
  283.  
  284. /* Dump the db as if it were a list of keys and strings as a list of strings */
  285. /* so the first string si a key, the seocnd is its string value */
  286. /* the next string is a key.. then value etc... so for a db like: */
  287. /* KEY: blah      STRING VALUE: hello */
  288. /* KEY: nym       STRING VALUE: goodbye */
  289. /* KEY: flim      STRINg VALUE: boo */
  290. /* Your string list would be: */
  291. /* "blah", "hello", "nym", "goodbye", "flim", "boo:" */
  292. EAPI char              **e_db_dump_multi_field(const char *file, const char *file2, int *num_ret);
  293.  
  294. /**
  295.  * e_db_dump_key_list - returns list of keys in a database
  296.  * @file: name of an Edb database file
  297.  * @num_ret: result pointer that returns the number of keys in the database
  298.  *
  299.  * This function returns a list of strings of the keys in the database.
  300.  * You must free the list and the strings in the list when done.
  301.  */
  302. EAPI char              **e_db_dump_key_list(const char *file, int *num_ret);
  303.  
  304. /**
  305.  * e_db_match_keys - returns list of keys matching a pattern
  306.  * @db: Edb database handle
  307.  * @pattern: key pattern to match
  308.  * @num_ret: result pointer that returns the number of keys in the database
  309.  *
  310.  * This function returns a list of strings of the keys in the database
  311.  * that match the given pattern. The pattern is a shell wildcard pattern.
  312.  * You must free the list and the strings in the list when done.
  313.  */
  314. EAPI char              **e_db_match_keys(E_DB_File *db, const char *pattern, int *num_ret);
  315.  
  316. /* Convenience macros to make setting and getting values form a db easy */ 
  317. #define E_DB_INT_SET(edb, key, val) \
  318. { E_DB_File *__edb; \
  319. __edb = e_db_open(edb); \
  320. if (__edb) { \
  321. e_db_int_set(__edb, key, val); \
  322. e_db_close(__edb); \
  323. }}
  324. #define E_DB_STR_SET(edb, key, str) \
  325. { E_DB_File *__edb; \
  326. __edb = e_db_open(edb); \
  327. if (__edb) { \
  328. e_db_str_set(__edb, key, str); \
  329. e_db_close(__edb); \
  330. }}
  331. #define E_DB_FLOAT_SET(edb, key, flt) \
  332. { E_DB_File *__edb; \
  333. __edb = e_db_open(edb); \
  334. if (__edb) { \
  335. e_db_float_set(__edb, key, flt); \
  336. e_db_close(__edb); \
  337. }}
  338. #define E_DB_INT_GET(edb, key, val, ok) \
  339. { E_DB_File *__edb; \
  340. __edb = e_db_open_read(edb); \
  341. if (__edb) { \
  342. ok = e_db_int_get(__edb, key, &val); \
  343. e_db_close(__edb); \
  344. }}
  345. #define E_DB_STR_GET(edb, key, str, ok) \
  346. { E_DB_File *__edb; \
  347. __edb = e_db_open_read(edb); \
  348. if (__edb) { \
  349. str = e_db_str_get(__edb, key); \
  350. ok = (int)str; \
  351. e_db_close(__edb); \
  352. }}
  353. #define E_DB_FLOAT_GET(edb, key, flt, ok) \
  354. { E_DB_File *__edb; \
  355. __edb = e_db_open_read(edb); \
  356. if (__edb) { \
  357. ok = e_db_float_get(__edb, key, &flt); \
  358. e_db_close(__edb); \
  359. }}
  360. #define E_DB_DEL(edb, key) \
  361. { E_DB_File *__edb; \
  362. __edb = e_db_open(edb); \
  363. if (__edb) { \
  364. e_db_data_del(__edb, key); \
  365. e_db_close(__edb); \
  366. }}
  367. #define E_DB_FLUSH e_db_runtime_flush();
  368.  
  369.  
  370. #ifdef __cplusplus
  371. }
  372. #endif                                                  /* __cplusplus */
  373.  
  374. #endif
  375.